home *** CD-ROM | disk | FTP | other *** search
/ Programming Languages Suite / ProgramD2.iso / Database Designers / Rational Rose 2000 / Rational Setup.EXE / common / lib / Win32 / ChangeNotify.pm next >
Text File  |  1998-11-15  |  5KB  |  190 lines
  1. #---------------------------------------------------------------------
  2. package Win32::ChangeNotify;
  3. #
  4. # Copyright 1998 Christopher J. Madsen
  5. #
  6. # Created: 3 Feb 1998 from the ActiveWare version
  7. #   (c) 1995 Microsoft Corporation. All rights reserved.
  8. #       Developed by ActiveWare Internet Corp., http://www.ActiveWare.com
  9. #
  10. #   Other modifications (c) 1997 by Gurusamy Sarathy <gsar@umich.edu>
  11. #
  12. # Author: Christopher J. Madsen <chris_madsen@geocities.com>
  13. # Version: 1.00 (6-Feb-1998)
  14. #
  15. # This program is free software; you can redistribute it and/or modify
  16. # it under the same terms as Perl itself.
  17. #
  18. # This program is distributed in the hope that it will be useful,
  19. # but WITHOUT ANY WARRANTY; without even the implied warranty of
  20. # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See either the
  21. # GNU General Public License or the Artistic License for more details.
  22. #
  23. # Monitor directory for changes
  24. #---------------------------------------------------------------------
  25.  
  26. $VERSION = '1.01';
  27.  
  28. use Carp;
  29. use Win32::IPC 1.00 '/./';      # Import everything
  30. require Exporter;
  31. require DynaLoader;
  32.  
  33. @ISA = qw(Exporter DynaLoader Win32::IPC);
  34. # Items to export into callers namespace by default. Note: do not export
  35. # names by default without a very good reason. Use EXPORT_OK instead.
  36. # Do not simply export all your public functions/methods/constants.
  37. @EXPORT = qw(
  38.     FILE_NOTIFY_CHANGE_ATTRIBUTES
  39.     FILE_NOTIFY_CHANGE_DIR_NAME
  40.     FILE_NOTIFY_CHANGE_FILE_NAME
  41.     FILE_NOTIFY_CHANGE_LAST_WRITE
  42.     FILE_NOTIFY_CHANGE_SECURITY
  43.     FILE_NOTIFY_CHANGE_SIZE
  44.     INFINITE
  45. );
  46. @EXPORT_OK = qw(
  47.   wait_all wait_any
  48. );
  49.  
  50. sub AUTOLOAD {
  51.     # This AUTOLOAD is used to 'autoload' constants from the constant()
  52.     # XS function.
  53.  
  54.     my($constname);
  55.     ($constname = $AUTOLOAD) =~ s/.*::_//;
  56.     #reset $! to zero to reset any current errors.
  57.     $!=0;
  58.     my $val = constant($constname, @_ ? $_[0] : 0);
  59.     if ($! != 0) {
  60.         ($pack,$file,$line) = caller;
  61.         die "Your vendor has not defined Win32::ChangeNotify macro $constname, used at $file line $line.";
  62.     }
  63.     eval "sub $AUTOLOAD { $val }";
  64.     goto &$AUTOLOAD;
  65. }
  66.  
  67. bootstrap Win32::ChangeNotify;
  68.  
  69. sub new {
  70.     my ($class,$path,$subtree,$filter) = @_;
  71.  
  72.     if ($filter =~ /\A[\s|A-Z_]+\Z/i) {
  73.         $filter = 0;
  74.         foreach (split(/[\s|]+/, $_[3])) {
  75.             $filter |= constant("FILE_NOTIFY_CHANGE_" . uc $_);
  76.             carp "Invalid filter $_" if $!;
  77.         }
  78.     }
  79.     _new($class,$path,$subtree,$filter);
  80. } # end new
  81.  
  82. sub Close { &close }
  83.  
  84. sub FindFirst { $_[0] = Win32::ChangeNotify->_new(@_[1..3]); }
  85.  
  86. sub FindNext { &reset }
  87.  
  88. 1;
  89. __END__
  90.  
  91. =head1 NAME
  92.  
  93. Win32::ChangeNotify - Monitor events related to files and directories
  94.  
  95. =head1 SYNOPSIS
  96.  
  97.     require Win32::ChangeNotify;
  98.  
  99.     $notify = Win32::ChangeNotify->new($Path,$WatchSubTree,$Events);
  100.     $notify->wait or warn "Something failed: $!\n";
  101.     # There has been a change.
  102.  
  103. =head1 DESCRIPTION
  104.  
  105. This module allows the user to use a Win32 change notification event
  106. object from Perl.  This allows the Perl program to monitor events
  107. relating to files and directory trees.
  108.  
  109. The C<wait> method and C<wait_all> & C<wait_any> functions are
  110. inherited from the L<"Win32::IPC"> module.
  111.  
  112. =head2 Methods
  113.  
  114. =over 4
  115.  
  116. =item $notify = Win32::ChangeNotify->new($path, $subtree, $filter)
  117.  
  118. Constructor for a new ChangeNotification object.  C<$path> is the
  119. directory to monitor.  If C<$subtree> is true, then all directories
  120. under C<$path> will be monitored.  C<$filter> indicates what events
  121. should trigger a notification.  It should be a string containing any
  122. of the following flags (separated by whitespace and/or C<|>).
  123.  
  124.    ATTRIBUTES    Any attribute change
  125.    DIR_NAME     Any directory name change
  126.    FILE_NAME    Any file name change (creating/deleting/renaming)
  127.    LAST_WRITE   Any change to a file's last write time
  128.    SECURITY     Any security descriptor change
  129.    SIZE         Any change in a file's size
  130.  
  131. (C<$filter> can also be an integer composed from the
  132. C<FILE_NOTIFY_CHANGE_*> constants.)
  133.  
  134. =item $notify->close
  135.  
  136. Shut down monitoring.  You could just C<undef $notify> instead (but
  137. C<close> works even if there are other copies of the object).  This
  138. happens automatically when your program exits.
  139.  
  140. =item $notify->reset
  141.  
  142. Resets the ChangeNotification object after a change has been detected.
  143. The object will become signalled again after the next change.  (It is
  144. OK to call this immediately after C<new>, but it is not required.)
  145.  
  146. =item $notify->wait
  147.  
  148. See L<"Win32::IPC">.  Remember to call C<reset> afterwards if you want
  149. to continue monitoring.
  150.  
  151. =back
  152.  
  153. =head2 Deprecated Functions and Methods
  154.  
  155. B<Win32::ChangeNotify> still supports the ActiveWare syntax, but its
  156. use is deprecated.
  157.  
  158. =over 4
  159.  
  160. =item FindFirst($Obj,$PathName,$WatchSubTree,$Filter)
  161.  
  162. Use
  163.  
  164.   $Obj = Win32::ChangeNotify->new($PathName,$WatchSubTree,$Filter)
  165.  
  166. instead.
  167.  
  168. =item $obj->FindNext()
  169.  
  170. Use C<$obj-E<gt>reset> instead.
  171.  
  172. =item $obj->Close()
  173.  
  174. Use C<$obj-E<gt>close> instead.
  175.  
  176. =back
  177.  
  178. =head1 AUTHOR
  179.  
  180. Christopher J. Madsen E<lt>F<chris_madsen@geocities.com>E<gt>
  181.  
  182. Loosely based on the original module by ActiveWare Internet Corp.,
  183. F<http://www.ActiveWare.com>
  184.  
  185. =cut
  186.  
  187. # Local Variables:
  188. # tmtrack-file-task: "Win32::ChangeNotify"
  189. # End:
  190.